<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML3.2 EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="DOCTEXT">
<TITLE>mpiexec</TITLE>
</HEAD>
<BODY BGCOLOR="FFFFFF">
<A NAME="mpiexec"><H1>mpiexec</H1></A>
Run an MPI program 
<H2>Synopsis</H2>
<PRE>
</PRE>
<PRE>
    mpiexec args executable pgmargs [ : args executable pgmargs ... ]
</PRE>

where <TT>args</TT> are command line arguments for <TT>mpiexec</TT> (see below),
<TT>executable</TT> is the name of an executable MPI program, and <TT>pgmargs
</TT>are command line arguments for the executable.  Multiple executables
can be specified by using the colon notation (for MPMD - Multiple Program
Multiple Data applications).   For example, the following command will run
the MPI program <TT>a.out</TT> on 4 processes:
<PRE>
    mpiexec -n 4 a.out
</PRE>

<P>
The MPI standard specifies the following arguments and their meanings:
<P>
<DL>
<DT><B>-n &lt;np&gt; </B><DD>Specify the number of processes to use

<DT><B>-host &lt;hostname&gt; </B><DD>Name of host on which to run processes

<DT><B>-arch &lt;architecture name&gt; </B><DD>Pick hosts with this architecture type

<DT><B>-wdir &lt;working directory&gt; </B><DD>cd to this one <EM>before</EM> running executable

<DT><B>-path &lt;pathlist&gt; </B><DD>use this to find the executable

<DT><B>-soft &lt;triplets&gt; </B><DD>comma separated triplets that specify requested numbers
of processes (see the MPI-2 specification for more details)

<DT><B>-file &lt;name&gt; </B><DD>implementation-defined specification file

<DT><B>-configfile &lt;name&gt; </B><DD>file containing specifications of host/program, 
one per line, with # as a comment indicator, e.g., the usual
mpiexec input, but with ":" replaced with a newline.  That is,
the configfile contains lines with -soft, -n etc.
</DL>
<P>
Additional arguments that are specific to the MPICH2 implementation
are discussed below.
<P>
Note that not all of these parameters are meaningful for all
systems.  For example, the <TT>gforker</TT> version of <TT>mpiexec</TT> creates all
processes on the same system on which it is running; in that case, the
<TT>-arch</TT> and <TT>-host</TT> options are ignored.
<P>
The colon character (<TT>:</TT>) may be used to separate different executables
for MPMD (multiple program multiple data) programming.  For example,
to run the program <TT>ocean</TT> on 4 processes and <TT>air</TT> on 8 processes, use:
<P>
<PRE>
    mpiexec -n 4 ocean : -n 8 air
</PRE>

<P>
<P>
<H2>MPICH2-Specific Arguments</H2>
<P>
Many of the implementations of process managers in MPICH2 support the
following arguments to <TT>mpiexec</TT>:
<P>
<DL>
<DT><B>-np &lt;num&gt; </B><DD>A synonym for the standard <TT>-n</TT> argument

<DT><B>-env &lt;name&gt; &lt;value&gt; </B><DD>Set the environment variable <TT>&lt;name&gt;</TT> to <TT>&lt;value&gt;</TT> for
the processes being run by <TT>mpiexec
</TT>
<DT><B>-envnone </B><DD>Pass no environment variables (other than ones specified with 
other <TT>-env</TT> or <TT>-genv</TT> arguments) to the processes being run by <TT>mpiexec</TT>.
By default, all environment
variables are provided to each MPI process (rationale: principle of
least surprise for the user)

<DT><B>-envlist &lt;list&gt; </B><DD>Pass the listed environment variables (names separated
by commas), with their current values, to the processes being run by
<TT>mpiexec</TT>.

<DT><B>-genv &lt;name&gt; &lt;value&gt; </B><DD>The <TT>-genv</TT> options have the same meaning as their
corresponding <TT>-env</TT> version, except they apply to all executables, not just 
the current executable (in the case that the colon syntax is used to specify
multiple execuables).

<DT><B>-genvnone </B><DD>Like <TT>-envnone</TT>, but for all executables

<DT><B>-genvlist &lt;list&gt; </B><DD>Like <TT>-envlist</TT>, but for all executables

<DT><B>-usize &lt;n&gt; </B><DD>Specify the value returned for the value of the attribute 
<TT>MPI_UNIVERSE_SIZE</TT>.

<DT><B>-l </B><DD>Label standard out and standard error (<TT>stdout</TT> and <TT>stderr</TT>) with 
the rank of the process

<DT><B>-maxtime &lt;n&gt; </B><DD>Set a timelimit of <TT>&lt;n&gt;</TT> seconds.

<DT><B>-exitinfo </B><DD>Provide more information on the reason each process exited if 
there is an abnormal exit
</DL>
<P>
<H2>Environment variables for mpiexec</H2>
The following environment variables are understood by some versions of
<TT>mpiexec</TT>.  The command line arguments have priority over these; that is,
if both the environment variable and command line argument are used, the
value specified by the command line argument is used.
<P>
<DL>
<DT><B>MPIEXEC_TIMEOUT  </B><DD>Maximum running time in seconds.  <TT>mpiexec</TT> will
terminate MPI programs that take longer than the value specified by
<TT>MPIEXEC_TIMEOUT</TT>.  

<DT><B>MPIEXEC_UNIVERSE_SIZE </B><DD>Set the universe size

<DT><B>MPIEXEC_PORT_RANGE </B><DD>Set the range of ports that <TT>mpiexec</TT> will use 
in communicating with the processes that it starts.  The format of 
this is <TT>&lt;low&gt;:&lt;high&gt;</TT>.  For example, to specify any port between
10000 and 10100, use <TT>10000:10100</TT>.  

<DT><B>MPICH_PORT_RANGE </B><DD>Has the same meaning as <TT>MPIEXEC_PORT_RANGE</TT> and 
is used if <TT>MPIEXEC_PORT_RANGE</TT> is not set.

<DT><B>MPIEXEC_PREFIX_DEFAULT </B><DD>If this environment variable is set, output
to standard output is prefixed by the rank in <TT>MPI_COMM_WORLD</TT> of the 
process and output to standard error is prefixed by the rank and the 
text <TT>(err)</TT>; both are followed by an angle bracket (<TT>&gt;</TT>).  If
this variable is not set, there is no prefix.

<DT><B>MPIEXEC_PREFIX_STDOUT </B><DD>Set the prefix used for lines sent to standard
output.  A <TT>%d</TT> is replaced with the rank in <TT>MPI_COMM_WORLD</TT>; a <TT>%w</TT> is 
replaced with an indication of which <TT>MPI_COMM_WORLD</TT> in MPI jobs that
involve multiple <TT>MPI_COMM_WORLD</TT>s (e.g., ones that use <TT>MPI_Comm_spawn</TT> or
<TT>MPI_Comm_connect</TT>).

<DT><B>MPIEXEC_PREFIX_STDERR </B><DD>Like <TT>MPIEXEC_PREFIX_STDOUT</TT>, but for standard error.
</DL>
<P>
<H2>Return Status</H2>
<TT>mpiexec</TT> returns the maximum of the exit status values of all of the
processes created by <TT>mpiexec</TT>.
<P>
<P><B>Location:</B>mpiexec.txt<P>
</BODY></HTML>
